package com.dms.modules.product.service;

import com.dms.modules.product.vo.ProductDetailVO;
import com.dms.modules.product.vo.ExperimentGroupInfo;
import com.dms.modules.product.entity.ProductRecommendationExperiment;
import java.util.List;
import java.util.Set;
import java.util.Map;
import java.time.LocalDateTime;

/**
 * 商品推荐服务接口
 */
public interface ProductRecommendationService {
    
    /**
     * 获取个性化推荐商品
     * @param userId 用户ID
     * @param limit 返回数量
     * @return 推荐商品列表
     */
    List<ProductDetailVO> getPersonalizedRecommendations(Long userId, Integer limit);
    
    /**
     * 获取基于浏览历史的推荐商品
     * @param userId 用户ID
     * @param limit 返回数量
     * @return 推荐商品列表
     */
    List<ProductDetailVO> getBrowseHistoryRecommendations(Long userId, Integer limit);
    
    /**
     * 获取基于收藏的推荐商品
     * @param userId 用户ID
     * @param limit 返回数量
     * @return 推荐商品列表
     */
    List<ProductDetailVO> getFavoriteRecommendations(Long userId, Integer limit);
    
    /**
     * 获取基于搜索历史的推荐商品
     * @param userId 用户ID
     * @param limit 返回数量
     * @return 推荐商品列表
     */
    List<ProductDetailVO> getSearchHistoryRecommendations(Long userId, Integer limit);
    
    /**
     * 获取相似商品推荐
     * @param productId 商品ID
     * @param limit 返回数量
     * @return 相似商品列表
     */
    List<ProductDetailVO> getSimilarProducts(Long productId, Integer limit);
    
    /**
     * 获取热门商品推荐
     * @param limit 返回数量
     * @return 热门商品列表
     */
    List<ProductDetailVO> getHotProducts(Integer limit);
    
    /**
     * 获取新品推荐
     * @param limit 返回数量
     * @return 新品列表
     */
    List<ProductDetailVO> getNewProducts(Integer limit);
    
    /**
     * 基于用户行为生成推荐
     * @param userProductIds 用户相关的商品ID集合
     * @param limit 返回数量
     * @return 推荐商品列表
     */
    List<ProductDetailVO> generateRecommendations(Set<Long> userProductIds, Integer limit);

    /**
     * 记录推荐结果
     * @param userId 用户ID
     * @param recommendationType 推荐类型
     * @param experimentGroup 实验分组
     * @param productIds 推荐商品ID列表
     */
    void recordRecommendation(Long userId, String recommendationType, 
            String experimentGroup, List<Long> productIds);
    
    /**
     * 记录用户点击
     * @param userId 用户ID
     * @param productId 商品ID
     */
    void recordUserClick(Long userId, Long productId);
    
    /**
     * 记录用户浏览
     * @param userId 用户ID
     * @param productId 商品ID
     */
    void recordUserView(Long userId, Long productId);
    
    /**
     * 获取推荐效果统计
     * @param recommendationType 推荐类型
     * @param experimentGroup 实验分组
     * @return 推荐效果指标
     */
    Map<String, Object> getRecommendationMetrics(String recommendationType, String experimentGroup);

    /**
     * 查询用户实验组信息
     * @param userIds 用户ID列表
     * @return Map<用户ID, 实验组信息>
     */
    Map<Long, ExperimentGroupInfo> queryUserExperimentGroups(List<Long> userIds);

    /**
     * 清除用户实验组缓存
     * @param userId 用户ID
     */
    void clearUserExperimentGroup(Long userId);

    /**
     * 重新分配用户实验组
     * @param userId 用户ID
     * @return 新的实验组信息
     */
    ExperimentGroupInfo reassignUserExperimentGroup(Long userId);

    /**
     * 获取所有活跃的实验配置
     * @return 实验配置列表
     */
    List<ProductRecommendationExperiment> getActiveExperiments();

    /**
     * 获取实验组的用户数量统计
     * @return Map<实验组, 用户数量>
     */
    Map<String, Long> getExperimentGroupUserCounts();

    /**
     * 获取实验组的效果指标统计
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return Map<实验组, 效果指标>
     */
    Map<String, Map<String, Object>> getExperimentGroupMetrics(LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 批量重置指定用户组的实验组
     * @param userIds 用户ID列表
     * @param targetGroup 目标实验组
     * @return 重置成功的用户数量
     */
    int reassignUsersToGroup(List<Long> userIds, String targetGroup);

    /**
     * 获取用户在指定时间段内的推荐历史
     * @param userId 用户ID
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return 推荐历史记录
     */
    List<Map<String, Object>> getUserRecommendationHistory(Long userId, LocalDateTime startTime, LocalDateTime endTime);
} 